From ab595621703ed5aac094a233ca2f01745259459e Mon Sep 17 00:00:00 2001
From: Alexander Mikhaylenko <alexm@gnome.org>
Date: Fri, 1 May 2020 20:10:52 +0500
Subject: [PATCH] headerbar: Document GtkBuilder child types, add a title
 example

---
 gtk/gtkheaderbar.c | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/gtk/gtkheaderbar.c b/gtk/gtkheaderbar.c
index 5414cb56ce..6952858ea0 100644
--- a/gtk/gtkheaderbar.c
+++ b/gtk/gtkheaderbar.c
@@ -57,6 +57,31 @@
  * titlebar widget of a #GtkWindow (see gtk_window_set_titlebar()), as it gives
  * features typical of titlebars while allowing the addition of child widgets.
  *
+ * The GtkHeaderBar implementation of the #GtkBuildable interface supports
+ * adding children at the start or end sides by specifying “start” or “end” as
+ * the “type” attribute of a <child> element, or setting the title widget by
+ * specifying “title” value.
+ *
+ * By default the GtkHeaderBar uses a #GtkLabel displaying the title of the
+ * window it is contained in as the title widget, equivalent to the following
+ * UI definition:
+ *
+ * |[
+ * <object class="GtkHeaderBar">
+ *   <property name="title-widget">
+ *     <object class="GtkLabel">
+ *       <property name="label" translatable="yes">Label</property>
+ *       <property name="single-line-mode">True</property>
+ *       <property name="ellipsize">end</property>
+ *       <property name="width-chars">5</property>
+ *       <style>
+ *         <class name="title"/>
+ *       </style>
+ *     </object>
+ *   </property>
+ * </object>
+ * ]|
+ *
  * # CSS nodes
  *
  * |[<!-- language="plain" -->
-- 
2.30.2